home *** CD-ROM | disk | FTP | other *** search
/ Australian Personal Computer 2002 November / CD 1 / APC0211D1.ISO / workshop / prog / files / ActivePerl-5.6.1.633-MSWin32.msi / _af7d047a048d04dd92a93ad11e040aec < prev    next >
Encoding:
Text File  |  2001-09-04  |  62.4 KB  |  1,943 lines

  1. If you read this file _as_is_, just ignore the funny characters you
  2. see. It is written in the POD format (see perlpod manpage) which is
  3. specially designed to be readable as is.
  4.  
  5. =head1 NAME
  6.  
  7. perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
  8.  
  9. =head1 SYNOPSIS
  10.  
  11. One can read this document in the following formats:
  12.  
  13.     man perlos2
  14.     view perl perlos2
  15.     explorer perlos2.html
  16.     info perlos2
  17.  
  18. to list some (not all may be available simultaneously), or it may
  19. be read I<as is>: either as F<README.os2>, or F<pod/perlos2.pod>.
  20.  
  21. To read the F<.INF> version of documentation (B<very> recommended)
  22. outside of OS/2, one needs an IBM's reader (may be available on IBM
  23. ftp sites (?)  (URL anyone?)) or shipped with PC DOS 7.0 and IBM's
  24. Visual Age C++ 3.5.
  25.  
  26. A copy of a Win* viewer is contained in the "Just add OS/2 Warp" package
  27.  
  28.   ftp://ftp.software.ibm.com/ps/products/os2/tools/jaow/jaow.zip
  29.  
  30. in F<?:\JUST_ADD\view.exe>. This gives one an access to EMX's 
  31. F<.INF> docs as well (text form is available in F</emx/doc> in 
  32. EMX's distribution).
  33.  
  34. Note that if you have F<lynx.exe> installed, you can follow WWW links
  35. from this document in F<.INF> format. If you have EMX docs installed 
  36. correctly, you can follow library links (you need to have C<view emxbook>
  37. working by setting C<EMXBOOK> environment variable as it is described
  38. in EMX docs).
  39.  
  40. =cut
  41.  
  42. Contents
  43.  
  44.  perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT. 
  45.  
  46.       NAME 
  47.       SYNOPSIS 
  48.       DESCRIPTION 
  49.          -  Target 
  50.          -  Other OSes 
  51.          -  Prerequisites 
  52.          -  Starting Perl programs under OS/2 (and DOS and...)
  53.          -  Starting OS/2 (and DOS) programs under Perl 
  54.       Frequently asked questions 
  55.          -  I cannot run external programs 
  56.          -  I cannot embed perl into my program, or use perl.dll from my program. 
  57.          -  `` and pipe-open do not work under DOS. 
  58.          -  Cannot start find.exe "pattern" file
  59.       INSTALLATION 
  60.          -  Automatic binary installation 
  61.          -  Manual binary installation 
  62.          -  Warning 
  63.       Accessing documentation 
  64.          -  OS/2 .INF file 
  65.          -  Plain text 
  66.          -  Manpages 
  67.          -  HTML 
  68.          -  GNU info files 
  69.          -  .PDF files 
  70.          -  LaTeX docs 
  71.       BUILD 
  72.          -  Prerequisites 
  73.          -  Getting perl source 
  74.          -  Application of the patches 
  75.          -  Hand-editing 
  76.          -  Making 
  77.          -  Testing 
  78.          -  Installing the built perl 
  79.          -  a.out-style build 
  80.       Build FAQ 
  81.          -  Some / became \ in pdksh. 
  82.          -  'errno' - unresolved external 
  83.          -  Problems with tr 
  84.          -  Some problem (forget which ;-) 
  85.          -  Library ... not found 
  86.          -  Segfault in make 
  87.       Specific (mis)features of EMX port 
  88.          -  setpriority, getpriority 
  89.          -  system() 
  90.          -  extproc on the first line
  91.          -  Additional modules: 
  92.          -  Prebuilt methods: 
  93.          -  Misfeatures 
  94.          -  Modifications 
  95.       Perl flavors 
  96.          -  perl.exe 
  97.          -  perl_.exe 
  98.          -  perl__.exe 
  99.          -  perl___.exe 
  100.          -  Why strange names? 
  101.          -  Why dynamic linking? 
  102.          -  Why chimera build? 
  103.       ENVIRONMENT 
  104.          -  PERLLIB_PREFIX 
  105.          -  PERL_BADLANG 
  106.          -  PERL_BADFREE 
  107.          -  PERL_SH_DIR 
  108.          -  TMP or TEMP 
  109.       Evolution 
  110.          -  Priorities 
  111.          -  DLL name mangling 
  112.          -  Threading 
  113.          -  Calls to external programs 
  114.          -  Memory allocation 
  115.          -  Threads
  116.       AUTHOR 
  117.       SEE ALSO 
  118.  
  119. =head1 DESCRIPTION
  120.  
  121. =head2 Target
  122.  
  123. The target is to make OS/2 the best supported platform for
  124. using/building/developing Perl and I<Perl applications>, as well as
  125. make Perl the best language to use under OS/2. The secondary target is
  126. to try to make this work under DOS and Win* as well (but not B<too> hard).
  127.  
  128. The current state is quite close to this target. Known limitations:
  129.  
  130. =over 5
  131.  
  132. =item *
  133.  
  134. Some *nix programs use fork() a lot; with the mostly useful flavors of perl
  135. for OS/2 (there are several built simultaneously) this is supported;
  136. some flavors do not.  Using fork() after I<use>ing dynamically loading
  137. extensions would not work with very old versions of EMX.
  138.  
  139. =item *
  140.  
  141. You need a separate perl executable F<perl__.exe> (see L<perl__.exe>)
  142. if you want to use PM code in your application (as Perl/Tk or OpenGL
  143. Perl modules do) without having a text-mode window present.
  144.  
  145. While using the standard F<perl.exe> from a text-mode window is possible
  146. too, I have seen cases when this causes degradation of the system stability.
  147. Using F<perl__.exe> avoids such a degradation.
  148.  
  149. =item *
  150.  
  151. There is no simple way to access WPS objects. The only way I know
  152. is via C<OS2::REXX> extension (see L<OS2::REXX>), and we do not have access to
  153. convenience methods of Object-REXX. (Is it possible at all? I know
  154. of no Object-REXX API.)  The C<SOM> extension (currently in alpha-text)
  155. may eventually remove this shortcoming.
  156.  
  157. =back
  158.  
  159. Please keep this list up-to-date by informing me about other items.
  160.  
  161. =head2 Other OSes
  162.  
  163. Since OS/2 port of perl uses a remarkable EMX environment, it can
  164. run (and build extensions, and - possibly - be built itself) under any
  165. environment which can run EMX. The current list is DOS,
  166. DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT. Out of many perl flavors,
  167. only one works, see L<"perl_.exe">.
  168.  
  169. Note that not all features of Perl are available under these
  170. environments. This depends on the features the I<extender> - most
  171. probably RSX - decided to implement.
  172.  
  173. Cf. L<Prerequisites>.
  174.  
  175. =head2 Prerequisites
  176.  
  177. =over 6
  178.  
  179. =item EMX
  180.  
  181. EMX runtime is required (may be substituted by RSX). Note that
  182. it is possible to make F<perl_.exe> to run under DOS without any
  183. external support by binding F<emx.exe>/F<rsx.exe> to it, see L<emxbind>. Note
  184. that under DOS for best results one should use RSX runtime, which
  185. has much more functions working (like C<fork>, C<popen> and so on). In
  186. fact RSX is required if there is no VCPI present. Note the
  187. RSX requires DPMI.
  188.  
  189. Only the latest runtime is supported, currently C<0.9d fix 03>. Perl may run
  190. under earlier versions of EMX, but this is not tested.
  191.  
  192. One can get different parts of EMX from, say
  193.  
  194.   http://www.leo.org/pub/comp/os/os2/leo/gnu/emx+gcc/
  195.   http://powerusersbbs.com/pub/os2/dev/   [EMX+GCC Development]
  196.   http://hobbes.nmsu.edu/pub/os2/dev/emx/v0.9d/
  197.  
  198. The runtime component should have the name F<emxrt.zip>.
  199.  
  200. B<NOTE>. It is enough to have F<emx.exe>/F<rsx.exe> on your path. One
  201. does not need to specify them explicitly (though this
  202.  
  203.   emx perl_.exe -de 0
  204.  
  205. will work as well.)
  206.  
  207. =item RSX
  208.  
  209. To run Perl on DPMI platforms one needs RSX runtime. This is
  210. needed under DOS-inside-OS/2, Win0.3*, Win0.95 and WinNT (see 
  211. L<"Other OSes">). RSX would not work with VCPI
  212. only, as EMX would, it requires DMPI.
  213.  
  214. Having RSX and the latest F<sh.exe> one gets a fully functional
  215. B<*nix>-ish environment under DOS, say, C<fork>, C<``> and
  216. pipe-C<open> work. In fact, MakeMaker works (for static build), so one
  217. can have Perl development environment under DOS. 
  218.  
  219. One can get RSX from, say
  220.  
  221.   ftp://ftp.cdrom.com/pub/os2/emx09c/contrib
  222.   ftp://ftp.uni-bielefeld.de/pub/systems/msdos/misc
  223.   ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/contrib
  224.  
  225. Contact the author on C<rainer@mathematik.uni-bielefeld.de>.
  226.  
  227. The latest F<sh.exe> with DOS hooks is available in
  228.  
  229.   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/
  230.  
  231. as F<sh_dos.zip> or under similar names starting with C<sh>, C<pdksh> etc.
  232.  
  233. =item HPFS
  234.  
  235. Perl does not care about file systems, but to install the whole perl
  236. library intact one needs a file system which supports long file names.
  237.  
  238. Note that if you do not plan to build the perl itself, it may be
  239. possible to fool EMX to truncate file names. This is not supported,
  240. read EMX docs to see how to do it.
  241.  
  242. =item pdksh
  243.  
  244. To start external programs with complicated command lines (like with
  245. pipes in between, and/or quoting of arguments), Perl uses an external
  246. shell. With EMX port such shell should be named F<sh.exe>, and located
  247. either in the wired-in-during-compile locations (usually F<F:/bin>),
  248. or in configurable location (see L<"PERL_SH_DIR">).
  249.  
  250. For best results use EMX pdksh. The standard binary (5.2.14 or later) runs
  251. under DOS (with L<RSX>) as well, see
  252.  
  253.   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/
  254.  
  255. =back
  256.  
  257. =head2 Starting Perl programs under OS/2 (and DOS and...)
  258.  
  259. Start your Perl program F<foo.pl> with arguments C<arg1 arg2 arg3> the
  260. same way as on any other platform, by
  261.  
  262.     perl foo.pl arg1 arg2 arg3
  263.  
  264. If you want to specify perl options C<-my_opts> to the perl itself (as
  265. opposed to to your program), use
  266.  
  267.     perl -my_opts foo.pl arg1 arg2 arg3
  268.  
  269. Alternately, if you use OS/2-ish shell, like CMD or 4os2, put
  270. the following at the start of your perl script:
  271.  
  272.     extproc perl -S -my_opts
  273.  
  274. rename your program to F<foo.cmd>, and start it by typing
  275.  
  276.     foo arg1 arg2 arg3
  277.  
  278. Note that because of stupid OS/2 limitations the full path of the perl
  279. script is not available when you use C<extproc>, thus you are forced to
  280. use C<-S> perl switch, and your script should be on the C<PATH>. As a plus
  281. side, if you know a full path to your script, you may still start it
  282. with 
  283.  
  284.     perl ../../blah/foo.cmd arg1 arg2 arg3
  285.  
  286. (note that the argument C<-my_opts> is taken care of by the C<extproc> line
  287. in your script, see L<C<extproc> on the first line>).
  288.  
  289. To understand what the above I<magic> does, read perl docs about C<-S>
  290. switch - see L<perlrun>, and cmdref about C<extproc>:
  291.  
  292.     view perl perlrun
  293.     man perlrun
  294.     view cmdref extproc
  295.     help extproc
  296.  
  297. or whatever method you prefer.
  298.  
  299. There are also endless possibilities to use I<executable extensions> of
  300. 4os2, I<associations> of WPS and so on... However, if you use
  301. *nixish shell (like F<sh.exe> supplied in the binary distribution),
  302. you need to follow the syntax specified in L<perlrun/"Switches">.
  303.  
  304. Note that B<-S> switch enables a search with additional extensions 
  305. F<.cmd>, F<.btm>, F<.bat>, F<.pl> as well.
  306.  
  307. =head2 Starting OS/2 (and DOS) programs under Perl
  308.  
  309. This is what system() (see L<perlfunc/system>), C<``> (see
  310. L<perlop/"I/O Operators">), and I<open pipe> (see L<perlfunc/open>)
  311. are for. (Avoid exec() (see L<perlfunc/exec>) unless you know what you
  312. do).
  313.  
  314. Note however that to use some of these operators you need to have a
  315. sh-syntax shell installed (see L<"Pdksh">, 
  316. L<"Frequently asked questions">), and perl should be able to find it
  317. (see L<"PERL_SH_DIR">).
  318.  
  319. The cases when the shell is used are:
  320.  
  321. =over
  322.  
  323. =item 1
  324.  
  325. One-argument system() (see L<perlfunc/system>), exec() (see L<perlfunc/exec>)
  326. with redirection or shell meta-characters;
  327.  
  328. =item 2
  329.  
  330. Pipe-open (see L<perlfunc/open>) with the command which contains redirection 
  331. or shell meta-characters;
  332.  
  333. =item 3
  334.  
  335. Backticks C<``> (see L<perlop/"I/O Operators">) with the command which contains
  336. redirection or shell meta-characters;
  337.  
  338. =item 4
  339.  
  340. If the executable called by system()/exec()/pipe-open()/C<``> is a script
  341. with the "magic" C<#!> line or C<extproc> line which specifies shell;
  342.  
  343. =item 5
  344.  
  345. If the executable called by system()/exec()/pipe-open()/C<``> is a script
  346. without "magic" line, and C<$ENV{EXECSHELL}> is set to shell;
  347.  
  348. =item 6
  349.  
  350. If the executable called by system()/exec()/pipe-open()/C<``> is not
  351. found;
  352.  
  353. =item 7
  354.  
  355. For globbing (see L<perlfunc/glob>, L<perlop/"I/O Operators">).
  356.  
  357. =back
  358.  
  359. For the sake of speed for a common case, in the above algorithms 
  360. backslashes in the command name are not considered as shell metacharacters.
  361.  
  362. Perl starts scripts which begin with cookies
  363. C<extproc> or C<#!> directly, without an intervention of shell.  Perl uses the
  364. same algorithm to find the executable as F<pdksh>: if the path
  365. on C<#!> line does not work, and contains C</>, then the executable
  366. is searched in F<.> and on C<PATH>.  To find arguments for these scripts
  367. Perl uses a different algorithm than F<pdksh>: up to 3 arguments are 
  368. recognized, and trailing whitespace is stripped.
  369.  
  370. If a script
  371. does not contain such a cooky, then to avoid calling F<sh.exe>, Perl uses
  372. the same algorithm as F<pdksh>: if C<$ENV{EXECSHELL}> is set, the
  373. script is given as the first argument to this command, if not set, then
  374. C<$ENV{COMSPEC} /c> is used (or a hardwired guess if C<$ENV{COMSPEC}> is
  375. not set).
  376.  
  377. If starting scripts directly, Perl will use exactly the same algorithm as for 
  378. the search of script given by B<-S> command-line option: it will look in
  379. the current directory, then on components of C<$ENV{PATH}> using the 
  380. following order of appended extensions: no extension, F<.cmd>, F<.btm>, 
  381. F<.bat>, F<.pl>.
  382.  
  383. Note that Perl will start to look for scripts only if OS/2 cannot start the
  384. specified application, thus C<system 'blah'> will not look for a script if 
  385. there is an executable file F<blah.exe> I<anywhere> on C<PATH>.  
  386.  
  387. Note also that executable files on OS/2 can have an arbitrary extension, 
  388. but F<.exe> will be automatically appended if no dot is present in the name.  
  389. The workaround as as simple as that:  since F<blah.> and F<blah> denote the 
  390. same file, to start an executable residing in file F<n:/bin/blah> (no 
  391. extension) give an argument C<n:/bin/blah.> (dot appended) to system().
  392.  
  393. Perl will correctly start PM programs from VIO (=text-mode) Perl process;
  394. the opposite is not true: when you start a non-PM program from a PM
  395. Perl process, it would not run it in a separate session.  If a separate
  396. session is desired, either ensure
  397. that shell will be used, as in C<system 'cmd /c myprog'>, or start it using
  398. optional arguments to system() documented in C<OS2::Process> module.  This
  399. is considered to be a feature.
  400.  
  401. =head1 Frequently asked questions
  402.  
  403. =head2 "It does not work"
  404.  
  405. Perl binary distributions come with a F<testperl.cmd> script which tries
  406. to detect common problems with misconfigured installations.  There is a
  407. pretty large chance it will discover which step of the installation you
  408. managed to goof.  C<;-)>
  409.  
  410. =head2 I cannot run external programs
  411.  
  412. =over 4
  413.  
  414. =item *
  415.  
  416. Did you run your programs with C<-w> switch? See 
  417. L<Starting OS/2 (and DOS) programs under Perl>.
  418.  
  419. =item *
  420.  
  421. Do you try to run I<internal> shell commands, like C<`copy a b`>
  422. (internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
  423. need to specify your shell explicitly, like C<`cmd /c copy a b`>,
  424. since Perl cannot deduce which commands are internal to your shell.
  425.  
  426. =back
  427.  
  428. =head2 I cannot embed perl into my program, or use F<perl.dll> from my
  429. program. 
  430.  
  431. =over 4
  432.  
  433. =item Is your program EMX-compiled with C<-Zmt -Zcrtdll>?
  434.  
  435. If not, you need to build a stand-alone DLL for perl. Contact me, I
  436. did it once. Sockets would not work, as a lot of other stuff.
  437.  
  438. =item Did you use L<ExtUtils::Embed>?
  439.  
  440. I had reports it does not work. Somebody would need to fix it.
  441.  
  442. =back
  443.  
  444. =head2 C<``> and pipe-C<open> do not work under DOS.
  445.  
  446. This may a variant of just L<"I cannot run external programs">, or a
  447. deeper problem. Basically: you I<need> RSX (see L<"Prerequisites">)
  448. for these commands to work, and you may need a port of F<sh.exe> which
  449. understands command arguments. One of such ports is listed in
  450. L<"Prerequisites"> under RSX. Do not forget to set variable
  451. C<L<"PERL_SH_DIR">> as well.
  452.  
  453. DPMI is required for RSX.
  454.  
  455. =head2 Cannot start C<find.exe "pattern" file>
  456.  
  457. Use one of
  458.  
  459.   system 'cmd', '/c', 'find "pattern" file';
  460.   `cmd /c 'find "pattern" file'`
  461.  
  462. This would start F<find.exe> via F<cmd.exe> via C<sh.exe> via
  463. C<perl.exe>, but this is a price to pay if you want to use
  464. non-conforming program. In fact F<find.exe> cannot be started at all
  465. using C library API only. Otherwise the following command-lines would be
  466. equivalent:
  467.  
  468.   find "pattern" file
  469.   find pattern file
  470.  
  471. =head1 INSTALLATION
  472.  
  473. =head2 Automatic binary installation
  474.  
  475. The most convenient way of installing a binary distribution of perl is via perl installer
  476. F<install.exe>. Just follow the instructions, and 99% of the
  477. installation blues would go away. 
  478.  
  479. Note however, that you need to have F<unzip.exe> on your path, and
  480. EMX environment I<running>. The latter means that if you just
  481. installed EMX, and made all the needed changes to F<Config.sys>,
  482. you may need to reboot in between. Check EMX runtime by running
  483.  
  484.     emxrev
  485.  
  486. A folder is created on your desktop which contains some useful
  487. objects.
  488.  
  489. B<Things not taken care of by automatic binary installation:>
  490.  
  491. =over 15
  492.  
  493. =item C<PERL_BADLANG>
  494.  
  495. may be needed if you change your codepage I<after> perl installation,
  496. and the new value is not supported by EMX. See L<"PERL_BADLANG">.
  497.  
  498. =item C<PERL_BADFREE>
  499.  
  500. see L<"PERL_BADFREE">.
  501.  
  502. =item F<Config.pm>
  503.  
  504. This file resides somewhere deep in the location you installed your
  505. perl library, find it out by 
  506.  
  507.   perl -MConfig -le "print $INC{'Config.pm'}"
  508.  
  509. While most important values in this file I<are> updated by the binary
  510. installer, some of them may need to be hand-edited. I know no such
  511. data, please keep me informed if you find one.
  512.  
  513. =back
  514.  
  515. B<NOTE>. Because of a typo the binary installer of 5.00305
  516. would install a variable C<PERL_SHPATH> into F<Config.sys>. Please
  517. remove this variable and put C<L<PERL_SH_DIR>> instead.
  518.  
  519. =head2 Manual binary installation
  520.  
  521. As of version 5.00305, OS/2 perl binary distribution comes split
  522. into 11 components. Unfortunately, to enable configurable binary
  523. installation, the file paths in the zip files are not absolute, but
  524. relative to some directory.
  525.  
  526. Note that the extraction with the stored paths is still necessary
  527. (default with unzip, specify C<-d> to pkunzip). However, you
  528. need to know where to extract the files. You need also to manually
  529. change entries in F<Config.sys> to reflect where did you put the
  530. files. Note that if you have some primitive unzipper (like
  531. pkunzip), you may get a lot of warnings/errors during
  532. unzipping. Upgrade to C<(w)unzip>.
  533.  
  534. Below is the sample of what to do to reproduce the configuration on my
  535. machine:
  536.  
  537. =over 3
  538.  
  539. =item Perl VIO and PM executables (dynamically linked)
  540.  
  541.   unzip perl_exc.zip *.exe *.ico -d f:/emx.add/bin
  542.   unzip perl_exc.zip *.dll -d f:/emx.add/dll
  543.  
  544. (have the directories with C<*.exe> on PATH, and C<*.dll> on
  545. LIBPATH);
  546.  
  547. =item Perl_ VIO executable (statically linked)
  548.  
  549.   unzip perl_aou.zip -d f:/emx.add/bin
  550.  
  551. (have the directory on PATH);
  552.  
  553. =item Executables for Perl utilities
  554.  
  555.   unzip perl_utl.zip -d f:/emx.add/bin
  556.  
  557. (have the directory on PATH);
  558.  
  559. =item Main Perl library
  560.  
  561.   unzip perl_mlb.zip -d f:/perllib/lib
  562.  
  563. If this directory is exactly the same as the prefix which was compiled
  564. into F<perl.exe>, you do not need to change
  565. anything. However, for perl to find the library if you use a different
  566. path, you need to
  567. C<set PERLLIB_PREFIX> in F<Config.sys>, see L<"PERLLIB_PREFIX">.
  568.  
  569. =item Additional Perl modules
  570.  
  571.   unzip perl_ste.zip -d f:/perllib/lib/site_perl/5.8.3/
  572.  
  573. Same remark as above applies.  Additionally, if this directory is not
  574. one of directories on @INC (and @INC is influenced by C<PERLLIB_PREFIX>), you
  575. need to put this
  576. directory and subdirectory F<./os2> in C<PERLLIB> or C<PERL5LIB>
  577. variable. Do not use C<PERL5LIB> unless you have it set already. See
  578. L<perl/"ENVIRONMENT">.
  579.  
  580. =item Tools to compile Perl modules
  581.  
  582.   unzip perl_blb.zip -d f:/perllib/lib
  583.  
  584. Same remark as for F<perl_ste.zip>.
  585.  
  586. =item Manpages for Perl and utilities
  587.  
  588.   unzip perl_man.zip -d f:/perllib/man
  589.  
  590. This directory should better be on C<MANPATH>. You need to have a
  591. working man to access these files.
  592.  
  593. =item Manpages for Perl modules
  594.  
  595.   unzip perl_mam.zip -d f:/perllib/man
  596.  
  597. This directory should better be on C<MANPATH>. You need to have a
  598. working man to access these files.
  599.  
  600. =item Source for Perl documentation
  601.  
  602.   unzip perl_pod.zip -d f:/perllib/lib
  603.  
  604. This is used by the C<perldoc> program (see L<perldoc>), and may be used to
  605. generate HTML documentation usable by WWW browsers, and
  606. documentation in zillions of other formats: C<info>, C<LaTeX>,
  607. C<Acrobat>, C<FrameMaker> and so on.
  608.  
  609. =item Perl manual in F<.INF> format
  610.  
  611.   unzip perl_inf.zip -d d:/os2/book
  612.  
  613. This directory should better be on C<BOOKSHELF>.
  614.  
  615. =item Pdksh
  616.  
  617.   unzip perl_sh.zip -d f:/bin
  618.  
  619. This is used by perl to run external commands which explicitly
  620. require shell, like the commands using I<redirection> and I<shell
  621. metacharacters>. It is also used instead of explicit F</bin/sh>.
  622.  
  623. Set C<PERL_SH_DIR> (see L<"PERL_SH_DIR">) if you move F<sh.exe> from
  624. the above location.
  625.  
  626. B<Note.> It may be possible to use some other sh-compatible shell
  627. (file globbing - if done via shell - may break).
  628.  
  629. =back
  630.  
  631. After you installed the components you needed and updated the
  632. F<Config.sys> correspondingly, you need to hand-edit
  633. F<Config.pm>. This file resides somewhere deep in the location you
  634. installed your perl library, find it out by
  635.  
  636.   perl -MConfig -le "print $INC{'Config.pm'}"
  637.  
  638. You need to correct all the entries which look like file paths (they
  639. currently start with C<f:/>).
  640.  
  641. =head2 B<Warning>
  642.  
  643. The automatic and manual perl installation leave precompiled paths
  644. inside perl executables. While these paths are overwriteable (see
  645. L<"PERLLIB_PREFIX">, L<"PERL_SH_DIR">), one may get better results by
  646. binary editing of paths inside the executables/DLLs.
  647.  
  648. =head1 Accessing documentation
  649.  
  650. Depending on how you built/installed perl you may have (otherwise
  651. identical) Perl documentation in the following formats:
  652.  
  653. =head2 OS/2 F<.INF> file
  654.  
  655. Most probably the most convenient form. Under OS/2 view it as
  656.  
  657.   view perl
  658.   view perl perlfunc
  659.   view perl less
  660.   view perl ExtUtils::MakeMaker
  661.  
  662. (currently the last two may hit a wrong location, but this may improve
  663. soon). Under Win* see L<"SYNOPSIS">.
  664.  
  665. If you want to build the docs yourself, and have I<OS/2 toolkit>, run
  666.  
  667.     pod2ipf > perl.ipf
  668.  
  669. in F</perllib/lib/pod> directory, then
  670.  
  671.     ipfc /inf perl.ipf
  672.  
  673. (Expect a lot of errors during the both steps.) Now move it on your
  674. BOOKSHELF path.
  675.  
  676. =head2 Plain text
  677.  
  678. If you have perl documentation in the source form, perl utilities
  679. installed, and GNU groff installed, you may use 
  680.  
  681.     perldoc perlfunc
  682.     perldoc less
  683.     perldoc ExtUtils::MakeMaker
  684.  
  685. to access the perl documentation in the text form (note that you may get
  686. better results using perl manpages).
  687.  
  688. Alternately, try running pod2text on F<.pod> files.
  689.  
  690. =head2 Manpages
  691.  
  692. If you have man installed on your system, and you installed perl
  693. manpages, use something like this:
  694.  
  695.     man perlfunc
  696.     man 3 less
  697.     man ExtUtils.MakeMaker
  698.  
  699. to access documentation for different components of Perl. Start with
  700.  
  701.     man perl
  702.  
  703. Note that dot (F<.>) is used as a package separator for documentation
  704. for packages, and as usual, sometimes you need to give the section - C<3>
  705. above - to avoid shadowing by the I<less(1) manpage>.
  706.  
  707. Make sure that the directory B<above> the directory with manpages is
  708. on our C<MANPATH>, like this
  709.  
  710.   set MANPATH=c:/man;f:/perllib/man
  711.  
  712. for Perl manpages in C<f:/perllib/man/man1/> etc.
  713.  
  714. =head2 HTML
  715.  
  716. If you have some WWW browser available, installed the Perl
  717. documentation in the source form, and Perl utilities, you can build
  718. HTML docs. Cd to directory with F<.pod> files, and do like this
  719.  
  720.     cd f:/perllib/lib/pod
  721.     pod2html
  722.  
  723. After this you can direct your browser the file F<perl.html> in this
  724. directory, and go ahead with reading docs, like this:
  725.  
  726.     explore file:///f:/perllib/lib/pod/perl.html
  727.  
  728. Alternatively you may be able to get these docs prebuilt from CPAN.
  729.  
  730. =head2 GNU C<info> files
  731.  
  732. Users of Emacs would appreciate it very much, especially with
  733. C<CPerl> mode loaded. You need to get latest C<pod2info> from C<CPAN>,
  734. or, alternately, prebuilt info pages.
  735.  
  736. =head2 F<.PDF> files
  737.  
  738. for C<Acrobat> are available on CPAN (for slightly old version of
  739. perl).
  740.  
  741. =head2 C<LaTeX> docs
  742.  
  743. can be constructed using C<pod2latex>.
  744.  
  745. =head1 BUILD
  746.  
  747. Here we discuss how to build Perl under OS/2. There is an alternative
  748. (but maybe older) view on http://www.shadow.net/~troc/os2perl.html
  749.  
  750. =head2 The short story
  751.  
  752. Assume that you are a seasoned porter, so are sure that all the necessary
  753. tools are already present on your system, and you know how to get the Perl
  754. source distribution.  Untar it, change to the extract directory, and
  755.  
  756.   gnupatch -p0 < os2\diff.configure
  757.   sh Configure -des -D prefix=f:/perllib
  758.   make
  759.   make test
  760.   make install
  761.   make aout_test
  762.   make aout_install
  763.  
  764. This puts the executables in f:/perllib/bin.  Manually move them to the
  765. C<PATH>, manually move the built F<perl*.dll> to C<LIBPATH> (here F<*> is
  766. a not-very-meaningful hex checksum), and run
  767.  
  768.   make installcmd INSTALLCMDDIR=d:/ir/on/path
  769.  
  770. What follows is a detailed guide through these steps.
  771.  
  772. =head2 Prerequisites
  773.  
  774. You need to have the latest EMX development environment, the full
  775. GNU tool suite (gawk renamed to awk, and GNU F<find.exe>
  776. earlier on path than the OS/2 F<find.exe>, same with F<sort.exe>, to
  777. check use
  778.  
  779.   find --version
  780.   sort --version
  781.  
  782. ). You need the latest version of F<pdksh> installed as F<sh.exe>.
  783.  
  784. Check that you have B<BSD> libraries and headers installed, and - 
  785. optionally - Berkeley DB headers and libraries, and crypt.
  786.  
  787. Possible locations to get this from are
  788.  
  789.   ftp://hobbes.nmsu.edu/os2/unix/
  790.   ftp://ftp.cdrom.com/pub/os2/unix/
  791.   ftp://ftp.cdrom.com/pub/os2/dev32/
  792.   ftp://ftp.cdrom.com/pub/os2/emx09c/
  793.  
  794. It is reported that the following archives contain enough utils to
  795. build perl: F<gnufutil.zip>, F<gnusutil.zip>, F<gnututil.zip>, F<gnused.zip>,
  796. F<gnupatch.zip>, F<gnuawk.zip>, F<gnumake.zip>, F<bsddev.zip> and
  797. F<ksh527rt.zip> (or a later version).  Note that all these utilities are
  798. known to be available from LEO:
  799.  
  800.   ftp://ftp.leo.org/pub/comp/os/os2/leo/gnu
  801.  
  802. If you have I<exactly the same version of Perl> installed already,
  803. make sure that no copies or perl are currently running.  Later steps
  804. of the build may fail since an older version of F<perl.dll> loaded into
  805. memory may be found. 
  806.  
  807. Also make sure that you have F</tmp> directory on the current drive,
  808. and F<.> directory in your C<LIBPATH>. One may try to correct the
  809. latter condition by
  810.  
  811.   set BEGINLIBPATH .
  812.  
  813. if you use something like F<CMD.EXE> or latest versions of F<4os2.exe>.
  814.  
  815. Make sure your gcc is good for C<-Zomf> linking: run C<omflibs>
  816. script in F</emx/lib> directory.
  817.  
  818. Check that you have link386 installed. It comes standard with OS/2,
  819. but may be not installed due to customization. If typing
  820.  
  821.   link386
  822.  
  823. shows you do not have it, do I<Selective install>, and choose C<Link
  824. object modules> in I<Optional system utilities/More>. If you get into
  825. link386 prompts, press C<Ctrl-C> to exit.
  826.  
  827. =head2 Getting perl source
  828.  
  829. You need to fetch the latest perl source (including developers
  830. releases). With some probability it is located in 
  831.  
  832.   http://www.perl.com/CPAN/src/5.0
  833.   http://www.perl.com/CPAN/src/5.0/unsupported
  834.  
  835. If not, you may need to dig in the indices to find it in the directory
  836. of the current maintainer.
  837.  
  838. Quick cycle of developers release may break the OS/2 build time to
  839. time, looking into 
  840.  
  841.   http://www.perl.com/CPAN/ports/os2/ilyaz/
  842.  
  843. may indicate the latest release which was publicly released by the
  844. maintainer. Note that the release may include some additional patches
  845. to apply to the current source of perl.
  846.  
  847. Extract it like this
  848.  
  849.   tar vzxf perl5.00409.tar.gz
  850.  
  851. You may see a message about errors while extracting F<Configure>. This is
  852. because there is a conflict with a similarly-named file F<configure>.
  853.  
  854. Change to the directory of extraction.
  855.  
  856. =head2 Application of the patches
  857.  
  858. You need to apply the patches in F<./os2/diff.*> like this:
  859.  
  860.   gnupatch -p0 < os2\diff.configure
  861.  
  862. You may also need to apply the patches supplied with the binary
  863. distribution of perl.
  864.  
  865. Note also that the F<db.lib> and F<db.a> from the EMX distribution
  866. are not suitable for multi-threaded compile (even single-threaded
  867. flavor of Perl uses multi-threaded C RTL, for
  868. compatibility with XFree86-OS/2). Get a corrected one from
  869.  
  870.   ftp://ftp.math.ohio-state.edu/pub/users/ilya/os2/db_mt.zip
  871.  
  872. =head2 Hand-editing
  873.  
  874. You may look into the file F<./hints/os2.sh> and correct anything
  875. wrong you find there. I do not expect it is needed anywhere.
  876.  
  877. =head2 Making
  878.  
  879.   sh Configure -des -D prefix=f:/perllib
  880.  
  881. C<prefix> means: where to install the resulting perl library. Giving
  882. correct prefix you may avoid the need to specify C<PERLLIB_PREFIX>,
  883. see L<"PERLLIB_PREFIX">.
  884.  
  885. I<Ignore the message about missing C<ln>, and about C<-c> option to
  886. tr>. The latter is most probably already fixed, if you see it and can trace
  887. where the latter spurious warning comes from, please inform me.
  888.  
  889. Now
  890.  
  891.   make
  892.  
  893. At some moment the built may die, reporting a I<version mismatch> or
  894. I<unable to run F<perl>>.  This means that you do not have F<.> in
  895. your LIBPATH, so F<perl.exe> cannot find the needed F<perl67B2.dll> (treat
  896. these hex digits as line noise).  After this is fixed the build
  897. should finish without a lot of fuss.
  898.  
  899. =head2 Testing
  900.  
  901. Now run
  902.  
  903.   make test
  904.  
  905. All tests should succeed (with some of them skipped).
  906.  
  907. Some tests may generate extra messages similar to
  908.  
  909. =over 4
  910.  
  911. =item A lot of C<bad free>
  912.  
  913. in database tests related to Berkeley DB. I<This should be fixed already.>
  914. If it persists, you may disable this warnings, see L<"PERL_BADFREE">.
  915.  
  916. =item Process terminated by SIGTERM/SIGINT
  917.  
  918. This is a standard message issued by OS/2 applications. *nix
  919. applications die in silence. It is considered to be a feature. One can
  920. easily disable this by appropriate sighandlers. 
  921.  
  922. However the test engine bleeds these message to screen in unexpected
  923. moments. Two messages of this kind I<should> be present during
  924. testing.
  925.  
  926. =back
  927.  
  928. To get finer test reports, call
  929.  
  930.   perl t/harness
  931.  
  932. The report with F<io/pipe.t> failing may look like this:
  933.  
  934.   Failed Test  Status Wstat Total Fail  Failed  List of failed
  935.   ------------------------------------------------------------
  936.   io/pipe.t                    12    1   8.33%  9
  937.   7 tests skipped, plus 56 subtests skipped.
  938.   Failed 1/195 test scripts, 99.49% okay. 1/6542 subtests failed, 99.98% okay.
  939.  
  940. The reasons for most important skipped tests are:
  941.  
  942. =over 8
  943.  
  944. =item F<op/fs.t>
  945.  
  946. =over 4
  947.  
  948. =item 18
  949.  
  950. Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
  951. provides only 2sec time granularity (for compatibility with FAT?).
  952.  
  953. =item 25
  954.  
  955. Checks C<truncate()> on a filehandle just opened for write - I do not
  956. know why this should or should not work.
  957.  
  958. =back
  959.  
  960. =item F<op/stat.t>
  961.  
  962. Checks C<stat()>. Tests:
  963.  
  964. =over 4
  965.  
  966. =item 4
  967.  
  968. Checks C<atime> and C<mtime> of C<stat()> - unfortunately, HPFS
  969. provides only 2sec time granularity (for compatibility with FAT?).
  970.  
  971. =back
  972.  
  973. =back
  974.  
  975. =head2 Installing the built perl
  976.  
  977. If you haven't yet moved perl.dll onto LIBPATH, do it now.
  978.  
  979. Run
  980.  
  981.   make install
  982.  
  983. It would put the generated files into needed locations. Manually put
  984. F<perl.exe>, F<perl__.exe> and F<perl___.exe> to a location on your
  985. PATH, F<perl.dll> to a location on your LIBPATH.
  986.  
  987. Run
  988.  
  989.   make installcmd INSTALLCMDDIR=d:/ir/on/path
  990.  
  991. to convert perl utilities to F<.cmd> files and put them on
  992. PATH. You need to put F<.EXE>-utilities on path manually. They are
  993. installed in C<$prefix/bin>, here C<$prefix> is what you gave to
  994. F<Configure>, see L<Making>.
  995.  
  996. =head2 C<a.out>-style build
  997.  
  998. Proceed as above, but make F<perl_.exe> (see L<"perl_.exe">) by
  999.  
  1000.   make perl_
  1001.  
  1002. test and install by
  1003.  
  1004.   make aout_test
  1005.   make aout_install
  1006.  
  1007. Manually put F<perl_.exe> to a location on your PATH.
  1008.  
  1009. B<Note.> The build process for C<perl_> I<does not know> about all the
  1010. dependencies, so you should make sure that anything is up-to-date,
  1011. say, by doing
  1012.  
  1013.   make perl_dll
  1014.  
  1015. first.
  1016.  
  1017. =head1 Build FAQ
  1018.  
  1019. =head2 Some C</> became C<\> in pdksh.
  1020.  
  1021. You have a very old pdksh. See L<Prerequisites>.
  1022.  
  1023. =head2 C<'errno'> - unresolved external
  1024.  
  1025. You do not have MT-safe F<db.lib>. See L<Prerequisites>.
  1026.  
  1027. =head2 Problems with tr or sed
  1028.  
  1029. reported with very old version of tr and sed.
  1030.  
  1031. =head2 Some problem (forget which ;-)
  1032.  
  1033. You have an older version of F<perl.dll> on your LIBPATH, which
  1034. broke the build of extensions.
  1035.  
  1036. =head2 Library ... not found
  1037.  
  1038. You did not run C<omflibs>. See L<Prerequisites>.
  1039.  
  1040. =head2 Segfault in make
  1041.  
  1042. You use an old version of GNU make. See L<Prerequisites>.
  1043.  
  1044. =head2 op/sprintf test failure
  1045.  
  1046. This can result from a bug in emx sprintf which was fixed in 0.9d fix 03.
  1047.  
  1048. =head1 Specific (mis)features of OS/2 port
  1049.  
  1050. =head2 C<setpriority>, C<getpriority>
  1051.  
  1052. Note that these functions are compatible with *nix, not with the older
  1053. ports of '94 - 95. The priorities are absolute, go from 32 to -95,
  1054. lower is quicker. 0 is the default priority.
  1055.  
  1056. B<WARNING>.  Calling C<getpriority> on a non-existing process can lock the
  1057. system before Warp3 fixpak22.
  1058.  
  1059. =head2 C<system()>
  1060.  
  1061. Multi-argument form of C<system()> allows an additional numeric
  1062. argument. The meaning of this argument is described in
  1063. L<OS2::Process>.
  1064.  
  1065. When finding a program to run, Perl first asks the OS to look for executables
  1066. on C<PATH>.  If not found, it looks for a script with possible extensions 
  1067. added in this order: no extension, F<.cmd>, F<.btm>, 
  1068. F<.bat>, F<.pl>.  If found, Perl checks the start of the file for magic
  1069. strings C<"#!"> and C<"extproc ">.  If found, Perl uses the rest of the
  1070. first line as the beginning of the command line to run this script.  The
  1071. only mangling done to the first line is extraction of arguments (currently
  1072. up to 3), and ignoring of the path-part of the "interpreter" name if it can't
  1073. be found using the full path.
  1074.  
  1075. E.g., C<system 'foo', 'bar', 'baz'> may lead Perl to finding
  1076. F<C:/emx/bin/foo.cmd> with the first line being
  1077.  
  1078.  extproc /bin/bash    -x   -c
  1079.  
  1080. If F</bin/bash> is not found, and appending of executable extensions to
  1081. F</bin/bash> does not help either, then Perl looks for an executable F<bash> on
  1082. C<PATH>.  If found in F<C:/emx.add/bin/bash.exe>, then the above system() is
  1083. translated to
  1084.  
  1085.   system qw(C:/emx.add/bin/bash.exe -x -c C:/emx/bin/foo.cmd bar baz)
  1086.  
  1087. One additional translation is performed: instead of F</bin/sh> Perl uses
  1088. the hardwired-or-customized shell (see C<L<"PERL_SH_DIR">>).
  1089.  
  1090. The above search for "interpreter" is recursive: if F<bash> executable is not
  1091. found, but F<bash.btm> is found, Perl will investigate its first line etc.
  1092. The only hardwired limit on the recursion depth is implicit: there is a limit
  1093. 4 on the number of additional arguments inserted before the actual arguments
  1094. given to system().  In particular, if no additional arguments are specified
  1095. on the "magic" first lines, then the limit on the depth is 4.
  1096.  
  1097. If Perl finds that the found executable is of different type than the
  1098. current session, it will start the new process in a separate session of
  1099. necessary type.  Call via C<OS2::Process> to disable this magic.
  1100.  
  1101. =head2 C<extproc> on the first line
  1102.  
  1103. If the first chars of a Perl script are C<"extproc ">, this line is treated
  1104. as C<#!>-line, thus all the switches on this line are processed (twice
  1105. if script was started via cmd.exe).  See L<perlrun/DESCRIPTION>.
  1106.  
  1107. =head2 Additional modules:
  1108.  
  1109. L<OS2::Process>, L<OS2::DLL>, L<OS2::REXX>, L<OS2::PrfDB>, L<OS2::ExtAttr>. These
  1110. modules provide access to additional numeric argument for C<system>
  1111. and to the information about the running process,
  1112. to DLLs having functions with REXX signature and to the REXX runtime, to
  1113. OS/2 databases in the F<.INI> format, and to Extended Attributes.
  1114.  
  1115. Two additional extensions by Andreas Kaiser, C<OS2::UPM>, and
  1116. C<OS2::FTP>, are included into C<ILYAZ> directory, mirrored on CPAN.
  1117.  
  1118. =head2 Prebuilt methods:
  1119.  
  1120. =over 4
  1121.  
  1122. =item C<File::Copy::syscopy>
  1123.  
  1124. used by C<File::Copy::copy>, see L<File::Copy>.
  1125.  
  1126. =item C<DynaLoader::mod2fname>
  1127.  
  1128. used by C<DynaLoader> for DLL name mangling.
  1129.  
  1130. =item  C<Cwd::current_drive()>
  1131.  
  1132. Self explanatory.
  1133.  
  1134. =item  C<Cwd::sys_chdir(name)>
  1135.  
  1136. leaves drive as it is.
  1137.  
  1138. =item  C<Cwd::change_drive(name)>
  1139.  
  1140. chanes the "current" drive.
  1141.  
  1142. =item  C<Cwd::sys_is_absolute(name)>
  1143.  
  1144. means has drive letter and is_rooted.
  1145.  
  1146. =item  C<Cwd::sys_is_rooted(name)>
  1147.  
  1148. means has leading C<[/\\]> (maybe after a drive-letter:).
  1149.  
  1150. =item  C<Cwd::sys_is_relative(name)>
  1151.  
  1152. means changes with current dir.
  1153.  
  1154. =item  C<Cwd::sys_cwd(name)>
  1155.  
  1156. Interface to cwd from EMX. Used by C<Cwd::cwd>.
  1157.  
  1158. =item  C<Cwd::sys_abspath(name, dir)>
  1159.  
  1160. Really really odious function to implement. Returns absolute name of
  1161. file which would have C<name> if CWD were C<dir>.  C<Dir> defaults to the
  1162. current dir.
  1163.  
  1164. =item  C<Cwd::extLibpath([type])>
  1165.  
  1166. Get current value of extended library search path. If C<type> is
  1167. present and I<true>, works with END_LIBPATH, otherwise with
  1168. C<BEGIN_LIBPATH>. 
  1169.  
  1170. =item  C<Cwd::extLibpath_set( path [, type ] )>
  1171.  
  1172. Set current value of extended library search path. If C<type> is
  1173. present and I<true>, works with END_LIBPATH, otherwise with
  1174. C<BEGIN_LIBPATH>. 
  1175.  
  1176. =item C<OS2::Error(do_harderror,do_exception)>
  1177.  
  1178. Returns    C<undef> if it was not called yet, otherwise bit 1 is
  1179. set if on the previous call do_harderror was enabled, bit
  1180. 2 is set if if on previous call do_exception was enabled.
  1181.  
  1182. This function enables/disables error popups associated with 
  1183. hardware errors (Disk not ready etc.) and software exceptions.
  1184.  
  1185. I know of no way to find out the state of popups I<before> the first call
  1186. to this function.
  1187.  
  1188. =item C<OS2::Errors2Drive(drive)>
  1189.  
  1190. Returns C<undef> if it was not called yet, otherwise return false if errors
  1191. were not requested to be written to a hard drive, or the drive letter if
  1192. this was requested.
  1193.  
  1194. This function may redirect error popups associated with hardware errors
  1195. (Disk not ready etc.) and software exceptions to the file POPUPLOG.OS2 at
  1196. the root directory of the specified drive.  Overrides OS2::Error() specified
  1197. by individual programs.  Given argument undef will disable redirection.
  1198.  
  1199. Has global effect, persists after the application exits.
  1200.  
  1201. I know of no way to find out the state of redirection of popups to the disk
  1202. I<before> the first call to this function.
  1203.  
  1204. =item OS2::SysInfo()
  1205.  
  1206. Returns a hash with system information. The keys of the hash are
  1207.  
  1208.     MAX_PATH_LENGTH, MAX_TEXT_SESSIONS, MAX_PM_SESSIONS,
  1209.     MAX_VDM_SESSIONS, BOOT_DRIVE, DYN_PRI_VARIATION,
  1210.     MAX_WAIT, MIN_SLICE, MAX_SLICE, PAGE_SIZE,
  1211.     VERSION_MAJOR, VERSION_MINOR, VERSION_REVISION,
  1212.     MS_COUNT, TIME_LOW, TIME_HIGH, TOTPHYSMEM, TOTRESMEM,
  1213.     TOTAVAILMEM, MAXPRMEM, MAXSHMEM, TIMER_INTERVAL,
  1214.     MAX_COMP_LENGTH, FOREGROUND_FS_SESSION,
  1215.     FOREGROUND_PROCESS
  1216.  
  1217. =item OS2::BootDrive()
  1218.  
  1219. Returns a letter without colon.
  1220.  
  1221. =item C<OS2::MorphPM(serve)>, C<OS2::UnMorphPM(serve)>
  1222.  
  1223. Transforms the current application into a PM application and back.
  1224. The argument true means that a real message loop is going to be served.
  1225. OS2::MorphPM() returns the PM message queue handle as an integer.
  1226.  
  1227. See L<"Centralized management of resources"> for additional details.
  1228.  
  1229. =item C<OS2::Serve_Messages(force)>
  1230.  
  1231. Fake on-demand retrieval of outstanding PM messages.  If C<force> is false,
  1232. will not dispatch messages if a real message loop is known to
  1233. be present.  Returns number of messages retrieved.
  1234.  
  1235. Dies with "QUITing..." if WM_QUIT message is obtained.
  1236.  
  1237. =item C<OS2::Process_Messages(force [, cnt])>
  1238.  
  1239. Retrieval of PM messages until window creation/destruction.  
  1240. If C<force> is false, will not dispatch messages if a real message loop
  1241. is known to be present.
  1242.  
  1243. Returns change in number of windows.  If C<cnt> is given,
  1244. it is incremented by the number of messages retrieved.
  1245.  
  1246. Dies with "QUITing..." if WM_QUIT message is obtained.
  1247.  
  1248. =item C<OS2::_control87(new,mask)>
  1249.  
  1250. the same as L<_control87(3)> of EMX.  Takes integers as arguments, returns
  1251. the previous coprocessor control word as an integer.  Only bits in C<new> which
  1252. are present in C<mask> are changed in the control word.
  1253.  
  1254. =item OS2::get_control87()
  1255.  
  1256. gets the coprocessor control word as an integer.
  1257.  
  1258. =item C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>
  1259.  
  1260. The variant of OS2::_control87() with default values good for
  1261. handling exception mask: if no C<mask>, uses exception mask part of C<new>
  1262. only.  If no C<new>, disables all the floating point exceptions.
  1263.  
  1264. See L<"Misfeatures"> for details.
  1265.  
  1266. =back
  1267.  
  1268. (Note that some of these may be moved to different libraries -
  1269. eventually).
  1270.  
  1271.  
  1272. =head2 Prebuilt variables:
  1273.  
  1274. =over 4
  1275.  
  1276. =item $OS2::emx_rev
  1277.  
  1278. same as _emx_rev of EMX, a string similar to C<0.9c>.
  1279.  
  1280. =item $OS2::emx_env
  1281.  
  1282. same as _emx_env of EMX, a number similar to 0x8001.
  1283.  
  1284. =item $OS2::os_ver
  1285.  
  1286. a number C<OS_MAJOR + 0.001 * OS_MINOR>.
  1287.  
  1288. =back
  1289.  
  1290. =head2 Misfeatures
  1291.  
  1292. =over 4
  1293.  
  1294. =item *
  1295.  
  1296. Since L<flock(3)> is present in EMX, but is not functional, it is 
  1297. emulated by perl.  To disable the emulations, set environment variable
  1298. C<USE_PERL_FLOCK=0>.
  1299.  
  1300. =item *
  1301.  
  1302. Here is the list of things which may be "broken" on
  1303. EMX (from EMX docs):
  1304.  
  1305. =over 4
  1306.  
  1307. =item *
  1308.  
  1309. The functions L<recvmsg(3)>, L<sendmsg(3)>, and L<socketpair(3)> are not
  1310. implemented.
  1311.  
  1312. =item *
  1313.  
  1314. L<sock_init(3)> is not required and not implemented.
  1315.  
  1316. =item *
  1317.  
  1318. L<flock(3)> is not yet implemented (dummy function).  (Perl has a workaround.)
  1319.  
  1320. =item *
  1321.  
  1322. L<kill(3)>:  Special treatment of PID=0, PID=1 and PID=-1 is not implemented.
  1323.  
  1324. =item *
  1325.  
  1326. L<waitpid(3)>:
  1327.  
  1328.       WUNTRACED
  1329.           Not implemented.
  1330.       waitpid() is not implemented for negative values of PID.
  1331.  
  1332. =back
  1333.  
  1334. Note that C<kill -9> does not work with the current version of EMX.
  1335.  
  1336. =item *
  1337.  
  1338. Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
  1339. of F<sh.exe> plague perl as well. 
  1340.  
  1341. In particular, uppercase letters do not work in C<[...]>-patterns with
  1342. the current pdksh.
  1343.  
  1344. =item *
  1345.  
  1346. Unix-domain sockets on OS/2 live in a pseudo-file-system C</sockets/...>.
  1347. To avoid a failure to create a socket with a name of a different form,
  1348. C<"/socket/"> is prepended to the socket name (unless it starts with this
  1349. already).
  1350.  
  1351. This may lead to problems later in case the socket is accessed via the
  1352. "usual" file-system calls using the "initial" name.
  1353.  
  1354. =item *
  1355.  
  1356. Apparently, IBM used a compiler (for some period of time around '95?) which
  1357. changes FP mask right and left.  This is not I<that> bad for IBM's
  1358. programs, but the same compiler was used for DLLs which are used with
  1359. general-purpose applications.  When these DLLs are used, the state of
  1360. floating-point flags in the application is not predictable.
  1361.  
  1362. What is much worse, some DLLs change the floating point flags when in
  1363. _DLLInitTerm() (e.g., F<TCP32IP>).  This means that even if you do not I<call>
  1364. any function in the DLL, just the act of loading this DLL will reset your
  1365. flags.  What is worse, the same compiler was used to compile some HOOK DLLs.
  1366. Given that HOOK dlls are executed in the context of I<all> the applications
  1367. in the system, this means a complete unpredictablity of floating point
  1368. flags on systems using such HOOK DLLs.  E.g., F<GAMESRVR.DLL> of B<DIVE>
  1369. origin changes the floating point flags on each write to the TTY of a VIO
  1370. (windowed text-mode) applications.
  1371.  
  1372. Some other (not completely debugged) situations when FP flags change include
  1373. some video drivers (?), and some operations related to creation of the windows.
  1374. People who code B<OpenGL> may have more experience on this.
  1375.  
  1376. Perl is generally used in the situation when all the floating-point
  1377. exceptions are ignored, as is the default under EMX.  If they are not ignored,
  1378. some benign Perl programs would get a C<SIGFPE> and would die a horrible death.
  1379.  
  1380. To circumvent this, Perl uses two hacks.  They help against I<one> type of
  1381. damage only: FP flags changed when loading a DLL.
  1382.  
  1383. One of the hacks is to disable floating point exceptions on startup (as
  1384. is the default with EMX).  This helps only with compile-time-linked DLLs
  1385. changing the flags before main() had a chance to be called.
  1386.  
  1387. The other hack is to restore FP flags after a call to dlopen().  This helps
  1388. against similar damage done by DLLs _DLLInitTerm() at runtime.  Currently
  1389. no way to switch these hacks off is provided.
  1390.  
  1391. =back
  1392.  
  1393. =head2 Modifications
  1394.  
  1395. Perl modifies some standard C library calls in the following ways:
  1396.  
  1397. =over 9
  1398.  
  1399. =item C<popen>
  1400.  
  1401. C<my_popen> uses F<sh.exe> if shell is required, cf. L<"PERL_SH_DIR">.
  1402.  
  1403. =item C<tmpnam>
  1404.  
  1405. is created using C<TMP> or C<TEMP> environment variable, via
  1406. C<tempnam>.
  1407.  
  1408. =item C<tmpfile>
  1409.  
  1410. If the current directory is not writable, file is created using modified
  1411. C<tmpnam>, so there may be a race condition.
  1412.  
  1413. =item C<ctermid>
  1414.  
  1415. a dummy implementation.
  1416.  
  1417. =item C<stat>
  1418.  
  1419. C<os2_stat> special-cases F</dev/tty> and F</dev/con>.
  1420.  
  1421. =item C<mkdir>, C<rmdir>
  1422.  
  1423. these EMX functions do not work if the path contains a trailing C</>.
  1424. Perl contains a workaround for this.
  1425.  
  1426. =item C<flock>
  1427.  
  1428. Since L<flock(3)> is present in EMX, but is not functional, it is 
  1429. emulated by perl.  To disable the emulations, set environment variable
  1430. C<USE_PERL_FLOCK=0>.
  1431.  
  1432. =back
  1433.  
  1434. =head2 Identifying DLLs
  1435.  
  1436. All the DLLs built with the current versions of Perl have ID strings
  1437. identifying the name of the extension, its version, and the version
  1438. of Perl required for this DLL.  Run C<bldlevel DLL-name> to find this
  1439. info.
  1440.  
  1441. =head2 Centralized management of resources
  1442.  
  1443. Since to call certain OS/2 API one needs to have a correctly initialized
  1444. C<Win> subsystem, OS/2-specific extensions may require getting C<HAB>s and
  1445. C<HMQ>s.  If an extension would do it on its own, another extension could
  1446. fail to initialize.
  1447.  
  1448. Perl provides a centralized management of these resources:
  1449.  
  1450. =over
  1451.  
  1452. =item C<HAB>
  1453.  
  1454. To get the HAB, the extension should call C<hab = perl_hab_GET()> in C.  After
  1455. this call is performed, C<hab> may be accessed as C<Perl_hab>.  There is
  1456. no need to release the HAB after it is used.
  1457.  
  1458. If by some reasons F<perl.h> cannot be included, use
  1459.  
  1460.   extern int Perl_hab_GET(void);
  1461.  
  1462. instead.
  1463.  
  1464. =item C<HMQ>
  1465.  
  1466. There are two cases:
  1467.  
  1468. =over
  1469.  
  1470. =item *
  1471.  
  1472. the extension needs an C<HMQ> only because some API will not work otherwise.
  1473. Use C<serve = 0> below.
  1474.  
  1475. =item *
  1476.  
  1477. the extension needs an C<HMQ> since it wants to engage in a PM event loop.
  1478. Use C<serve = 1> below.
  1479.  
  1480. =back
  1481.  
  1482. To get an C<HMQ>, the extension should call C<hmq = perl_hmq_GET(serve)> in C.
  1483. After this call is performed, C<hmq> may be accessed as C<Perl_hmq>.
  1484.  
  1485. To signal to Perl that HMQ is not needed any more, call
  1486. C<perl_hmq_UNSET(serve)>.  Perl process will automatically morph/unmorph itself
  1487. into/from a PM process if HMQ is needed/not-needed.  Perl will automatically
  1488. enable/disable C<WM_QUIT> message during shutdown if the message queue is
  1489. served/not-served.
  1490.  
  1491. B<NOTE>.  If during a shutdown there is a message queue which did not disable
  1492. WM_QUIT, and which did not process the received WM_QUIT message, the
  1493. shutdown will be automatically cancelled.  Do not call C<perl_hmq_GET(1)>
  1494. unless you are going to process messages on an orderly basis.
  1495.  
  1496. =back
  1497.  
  1498. =head1 Perl flavors
  1499.  
  1500. Because of idiosyncrasies of OS/2 one cannot have all the eggs in the
  1501. same basket (though EMX environment tries hard to overcome this
  1502. limitations, so the situation may somehow improve). There are 4
  1503. executables for Perl provided by the distribution:
  1504.  
  1505. =head2 F<perl.exe>
  1506.  
  1507. The main workhorse. This is a chimera executable: it is compiled as an
  1508. C<a.out>-style executable, but is linked with C<omf>-style dynamic
  1509. library F<perl.dll>, and with dynamic CRT DLL. This executable is a
  1510. VIO application.
  1511.  
  1512. It can load perl dynamic extensions, and it can fork().
  1513.  
  1514. B<Note.> Keep in mind that fork() is needed to open a pipe to yourself.
  1515.  
  1516. =head2 F<perl_.exe>
  1517.  
  1518. This is a statically linked C<a.out>-style executable. It cannot
  1519. load dynamic Perl extensions. The executable supplied in binary
  1520. distributions has a lot of extensions prebuilt, thus the above restriction is 
  1521. important only if you use custom-built extensions. This executable is a VIO
  1522. application.
  1523.  
  1524. I<This is the only executable with does not require OS/2.> The
  1525. friends locked into C<M$> world would appreciate the fact that this
  1526. executable runs under DOS, Win0.3*, Win0.95 and WinNT with an
  1527. appropriate extender. See L<"Other OSes">.
  1528.  
  1529. =head2 F<perl__.exe>
  1530.  
  1531. This is the same executable as F<perl___.exe>, but it is a PM
  1532. application. 
  1533.  
  1534. B<Note.> Usually (unless explicitly redirected during the startup)
  1535. STDIN, STDERR, and STDOUT of a PM
  1536. application are redirected to F<nul>. However, it is possible to I<see>
  1537. them if you start C<perl__.exe> from a PM program which emulates a
  1538. console window, like I<Shell mode> of Emacs or EPM. Thus it I<is
  1539. possible> to use Perl debugger (see L<perldebug>) to debug your PM
  1540. application (but beware of the message loop lockups - this will not
  1541. work if you have a message queue to serve, unless you hook the serving
  1542. into the getc() function of the debugger).
  1543.  
  1544. Another way to see the output of a PM program is to run it as
  1545.  
  1546.   pm_prog args 2>&1 | cat -
  1547.  
  1548. with a shell I<different> from F<cmd.exe>, so that it does not create
  1549. a link between a VIO session and the session of C<pm_porg>.  (Such a link
  1550. closes the VIO window.)  E.g., this works with F<sh.exe> - or with Perl!
  1551.  
  1552.   open P, 'pm_prog args 2>&1 |' or die;
  1553.   print while <P>;
  1554.  
  1555. The flavor F<perl__.exe> is required if you want to start your program without
  1556. a VIO window present, but not C<detach>ed (run C<help detach> for more info).
  1557. Very useful for extensions which use PM, like C<Perl/Tk> or C<OpenGL>.
  1558.  
  1559. =head2 F<perl___.exe>
  1560.  
  1561. This is an C<omf>-style executable which is dynamically linked to
  1562. F<perl.dll> and CRT DLL. I know no advantages of this executable
  1563. over C<perl.exe>, but it cannot fork() at all. Well, one advantage is
  1564. that the build process is not so convoluted as with C<perl.exe>.
  1565.  
  1566. It is a VIO application.
  1567.  
  1568. =head2 Why strange names?
  1569.  
  1570. Since Perl processes the C<#!>-line (cf. 
  1571. L<perlrun/DESCRIPTION>, L<perlrun/Switches>,
  1572. L<perldiag/"Not a perl script">, 
  1573. L<perldiag/"No Perl script found in input">), it should know when a
  1574. program I<is a Perl>. There is some naming convention which allows
  1575. Perl to distinguish correct lines from wrong ones. The above names are
  1576. almost the only names allowed by this convention which do not contain
  1577. digits (which have absolutely different semantics).
  1578.  
  1579. =head2 Why dynamic linking?
  1580.  
  1581. Well, having several executables dynamically linked to the same huge
  1582. library has its advantages, but this would not substantiate the
  1583. additional work to make it compile. The reason is the complicated-to-developers
  1584. but very quick and convenient-to-users "hard" dynamic linking used by OS/2.
  1585.  
  1586. There are two distinctive features of the dyna-linking model of OS/2:
  1587. all the references to external functions are resolved at the compile time;
  1588. there is no runtime fixup of the DLLs after they are loaded into memory.
  1589. The first feature is an enormous advantage over other models: it avoids
  1590. conflicts when several DLLs used by an application export entries with
  1591. the same name.  In such cases "other" models of dyna-linking just choose
  1592. between these two entry points using some random criterion - with predictable
  1593. disasters as results.  But it is the second feature which requires the build
  1594. of F<perl.dll>.
  1595.  
  1596. The address tables of DLLs are patched only once, when they are
  1597. loaded. The addresses of the entry points into DLLs are guaranteed to be
  1598. the same for all the programs which use the same DLL.  This removes the
  1599. runtime fixup - once DLL is loaded, its code is read-only.
  1600.  
  1601. While this allows some (significant?) performance advantages, this makes life
  1602. much harder for developers, since the above scheme makes it impossible
  1603. for a DLL to be "linked" to a symbol in the F<.EXE> file.  Indeed, this
  1604. would need a DLL to have different relocations tables for the
  1605. (different) executables which use this DLL.
  1606.  
  1607. However, a dynamically loaded Perl extension is forced to use some symbols
  1608. from the perl
  1609. executable, e.g., to know how to find the arguments to the functions:
  1610. the arguments live on the perl
  1611. internal evaluation stack. The solution is to put the main code of
  1612. the interpreter into a DLL, and make the F<.EXE> file which just loads
  1613. this DLL into memory and supplies command-arguments.  The extension DLL
  1614. cannot link to symbols in F<.EXE>, but it has no problem linking
  1615. to symbols in the F<.DLL>.
  1616.  
  1617. This I<greatly> increases the load time for the application (as well as
  1618. complexity of the compilation). Since interpreter is in a DLL,
  1619. the C RTL is basically forced to reside in a DLL as well (otherwise
  1620. extensions would not be able to use CRT).  There are some advantages if
  1621. you use different flavors of perl, such as running F<perl.exe> and
  1622. F<perl__.exe> simultaneously: they share the memory of F<perl.dll>.
  1623.  
  1624. B<NOTE>.  There is one additional effect which makes DLLs more wasteful:
  1625. DLLs are loaded in the shared memory region, which is a scarse resource
  1626. given the 512M barrier of the "standard" OS/2 virtual memory.  The code of
  1627. F<.EXE> files is also shared by all the processes which use the particular
  1628. F<.EXE>, but they are "shared in the private address space of the process";
  1629. this is possible because the address at which different sections
  1630. of the F<.EXE> file are loaded is decided at compile-time, thus all the
  1631. processes have these sections loaded at same addresses, and no fixup
  1632. of internal links inside the F<.EXE> is needed.
  1633.  
  1634. Since DLLs may be loaded at run time, to have the same mechanism for for DLLs
  1635. one needs to have the address range of I<any of the loaded> DLLs in the
  1636. system to be available I<in all the processes> which did not load a particular
  1637. DLL yet.  This is why the DLLs are mapped to the shared memory region.
  1638.  
  1639. =head2 Why chimera build?
  1640.  
  1641. Current EMX environment does not allow DLLs compiled using Unixish
  1642. C<a.out> format to export symbols for data (or at least some types of
  1643. data). This forces C<omf>-style compile of F<perl.dll>.
  1644.  
  1645. Current EMX environment does not allow F<.EXE> files compiled in
  1646. C<omf> format to fork(). fork() is needed for exactly three Perl
  1647. operations:
  1648.  
  1649. =over 4
  1650.  
  1651. =item *
  1652.  
  1653. explicit fork() in the script, 
  1654.  
  1655. =item *
  1656.  
  1657. C<open FH, "|-">
  1658.  
  1659. =item *
  1660.  
  1661. C<open FH, "-|">, in other words, opening pipes to itself.
  1662.  
  1663. =back
  1664.  
  1665. While these operations are not questions of life and death, they are
  1666. needed for a lot of
  1667. useful scripts. This forces C<a.out>-style compile of
  1668. F<perl.exe>.
  1669.  
  1670.  
  1671. =head1 ENVIRONMENT
  1672.  
  1673. Here we list environment variables with are either OS/2- and DOS- and
  1674. Win*-specific, or are more important under OS/2 than under other OSes.
  1675.  
  1676. =head2 C<PERLLIB_PREFIX>
  1677.  
  1678. Specific for EMX port. Should have the form
  1679.  
  1680.   path1;path2
  1681.  
  1682. or
  1683.  
  1684.   path1 path2
  1685.  
  1686. If the beginning of some prebuilt path matches F<path1>, it is
  1687. substituted with F<path2>.
  1688.  
  1689. Should be used if the perl library is moved from the default
  1690. location in preference to C<PERL(5)LIB>, since this would not leave wrong
  1691. entries in @INC.  For example, if the compiled version of perl looks for @INC
  1692. in F<f:/perllib/lib>, and you want to install the library in
  1693. F<h:/opt/gnu>, do
  1694.  
  1695.   set PERLLIB_PREFIX=f:/perllib/lib;h:/opt/gnu
  1696.  
  1697. This will cause Perl with the prebuilt @INC of
  1698.  
  1699.   f:/perllib/lib/5.00553/os2
  1700.   f:/perllib/lib/5.00553
  1701.   f:/perllib/lib/site_perl/5.00553/os2
  1702.   f:/perllib/lib/site_perl/5.00553
  1703.   .
  1704.  
  1705. to use the following @INC:
  1706.  
  1707.   h:/opt/gnu/5.00553/os2
  1708.   h:/opt/gnu/5.00553
  1709.   h:/opt/gnu/site_perl/5.00553/os2
  1710.   h:/opt/gnu/site_perl/5.00553
  1711.   .
  1712.  
  1713. =head2 C<PERL_BADLANG>
  1714.  
  1715. If 0, perl ignores setlocale() failing. May be useful with some
  1716. strange I<locale>s.
  1717.  
  1718. =head2 C<PERL_BADFREE>
  1719.  
  1720. If 0, perl would not warn of in case of unwarranted free(). With older
  1721. perls this might be
  1722. useful in conjunction with the module DB_File, which was buggy when
  1723. dynamically linked and OMF-built.
  1724.  
  1725. Should not be set with newer Perls, since this may hide some I<real> problems.
  1726.  
  1727. =head2 C<PERL_SH_DIR>
  1728.  
  1729. Specific for EMX port. Gives the directory part of the location for
  1730. F<sh.exe>.
  1731.  
  1732. =head2 C<USE_PERL_FLOCK>
  1733.  
  1734. Specific for EMX port. Since L<flock(3)> is present in EMX, but is not 
  1735. functional, it is emulated by perl.  To disable the emulations, set 
  1736. environment variable C<USE_PERL_FLOCK=0>.
  1737.  
  1738. =head2 C<TMP> or C<TEMP>
  1739.  
  1740. Specific for EMX port. Used as storage place for temporary files.
  1741.  
  1742. =head1 Evolution
  1743.  
  1744. Here we list major changes which could make you by surprise.
  1745.  
  1746. =head2 Priorities
  1747.  
  1748. C<setpriority> and C<getpriority> are not compatible with earlier
  1749. ports by Andreas Kaiser. See C<"setpriority, getpriority">.
  1750.  
  1751. =head2 DLL name mangling
  1752.  
  1753. With the release 5.003_01 the dynamically loadable libraries
  1754. should be rebuilt when a different version of Perl is compiled. In particular,
  1755. DLLs (including F<perl.dll>) are now created with the names
  1756. which contain a checksum, thus allowing workaround for OS/2 scheme of
  1757. caching DLLs.
  1758.  
  1759. It may be possible to code a simple workaround which would 
  1760.  
  1761. =over
  1762.  
  1763. =item *
  1764.  
  1765. find the old DLLs looking through the old @INC;
  1766.  
  1767. =item *
  1768.  
  1769. mangle the names according to the scheme of new perl and copy the DLLs to
  1770. these names;
  1771.  
  1772. =item *
  1773.  
  1774. edit the internal C<LX> tables of DLL to reflect the change of the name
  1775. (probably not needed for Perl extension DLLs, since the internally coded names
  1776. are not used for "specific" DLLs, they used only for "global" DLLs).
  1777.  
  1778. =item *
  1779.  
  1780. edit the internal C<IMPORT> tables and change the name of the "old"
  1781. F<perl????.dll> to the "new" F<perl????.dll>.
  1782.  
  1783. =back
  1784.  
  1785. =head2 Threading
  1786.  
  1787. As of release 5.003_01 perl is linked to multithreaded C RTL
  1788. DLL.  If perl itself is not compiled multithread-enabled, so will not be perl's
  1789. malloc(). However, extensions may use multiple thread on their own
  1790. risk. 
  1791.  
  1792. This was needed to compile C<Perl/Tk> for XFree86-OS/2 out-of-the-box, and
  1793. link with DLLs for other useful libraries, which typically are compiled
  1794. with C<-Zmt -Zcrtdll>.
  1795.  
  1796. =head2 Calls to external programs
  1797.  
  1798. Due to a popular demand the perl external program calling has been
  1799. changed wrt Andreas Kaiser's port.  I<If> perl needs to call an
  1800. external program I<via shell>, the F<f:/bin/sh.exe> will be called, or
  1801. whatever is the override, see L<"PERL_SH_DIR">.
  1802.  
  1803. Thus means that you need to get some copy of a F<sh.exe> as well (I
  1804. use one from pdksh). The path F<F:/bin> above is set up automatically during
  1805. the build to a correct value on the builder machine, but is
  1806. overridable at runtime,
  1807.  
  1808. B<Reasons:> a consensus on C<perl5-porters> was that perl should use
  1809. one non-overridable shell per platform. The obvious choices for OS/2
  1810. are F<cmd.exe> and F<sh.exe>. Having perl build itself would be impossible
  1811. with F<cmd.exe> as a shell, thus I picked up C<sh.exe>. This assures almost
  1812. 100% compatibility with the scripts coming from *nix. As an added benefit 
  1813. this works as well under DOS if you use DOS-enabled port of pdksh 
  1814. (see L<"Prerequisites">).
  1815.  
  1816. B<Disadvantages:> currently F<sh.exe> of pdksh calls external programs
  1817. via fork()/exec(), and there is I<no> functioning exec() on
  1818. OS/2. exec() is emulated by EMX by an asynchronous call while the caller
  1819. waits for child completion (to pretend that the C<pid> did not change). This
  1820. means that 1 I<extra> copy of F<sh.exe> is made active via fork()/exec(),
  1821. which may lead to some resources taken from the system (even if we do
  1822. not count extra work needed for fork()ing).
  1823.  
  1824. Note that this a lesser issue now when we do not spawn F<sh.exe>
  1825. unless needed (metachars found).
  1826.  
  1827. One can always start F<cmd.exe> explicitly via
  1828.  
  1829.   system 'cmd', '/c', 'mycmd', 'arg1', 'arg2', ...
  1830.  
  1831. If you need to use F<cmd.exe>, and do not want to hand-edit thousands of your
  1832. scripts, the long-term solution proposed on p5-p is to have a directive
  1833.  
  1834.   use OS2::Cmd;
  1835.  
  1836. which will override system(), exec(), C<``>, and
  1837. C<open(,'...|')>. With current perl you may override only system(),
  1838. readpipe() - the explicit version of C<``>, and maybe exec(). The code
  1839. will substitute the one-argument call to system() by
  1840. C<CORE::system('cmd.exe', '/c', shift)>.
  1841.  
  1842. If you have some working code for C<OS2::Cmd>, please send it to me,
  1843. I will include it into distribution. I have no need for such a module, so
  1844. cannot test it.
  1845.  
  1846. For the details of the current situation with calling external programs,
  1847. see L<Starting OS/2 (and DOS) programs under Perl>.  Set us mention a couple
  1848. of features:
  1849.  
  1850. =over 4
  1851.  
  1852. =item *
  1853.  
  1854. External scripts may be called by their basename.  Perl will try the same
  1855. extensions as when processing B<-S> command-line switch.
  1856.  
  1857. =item *
  1858.  
  1859. External scripts starting with C<#!> or C<extproc > will be executed directly,
  1860. without calling the shell, by calling the program specified on the rest of
  1861. the first line.
  1862.  
  1863. =back
  1864.  
  1865. =head2 Memory allocation
  1866.  
  1867. Perl uses its own malloc() under OS/2 - interpreters are usually malloc-bound
  1868. for speed, but perl is not, since its malloc is lightning-fast.
  1869. Perl-memory-usage-tuned benchmarks show that Perl's malloc is 5 times quicker
  1870. than EMX one.  I do not have convincing data about memory footprint, but
  1871. a (pretty random) benchmark showed that Perl's one is 5% better.
  1872.  
  1873. Combination of perl's malloc() and rigid DLL name resolution creates
  1874. a special problem with library functions which expect their return value to
  1875. be free()d by system's free(). To facilitate extensions which need to call 
  1876. such functions, system memory-allocation functions are still available with
  1877. the prefix C<emx_> added. (Currently only DLL perl has this, it should 
  1878. propagate to F<perl_.exe> shortly.)
  1879.  
  1880. =head2 Threads
  1881.  
  1882. One can build perl with thread support enabled by providing C<-D usethreads>
  1883. option to F<Configure>.  Currently OS/2 support of threads is very 
  1884. preliminary.
  1885.  
  1886. Most notable problems: 
  1887.  
  1888. =over 4
  1889.  
  1890. =item C<COND_WAIT> 
  1891.  
  1892. may have a race condition.  Needs a reimplementation (in terms of chaining
  1893. waiting threads, with the linked list stored in per-thread structure?).
  1894.  
  1895. =item F<os2.c>
  1896.  
  1897. has a couple of static variables used in OS/2-specific functions.  (Need to be
  1898. moved to per-thread structure, or serialized?)
  1899.  
  1900. =back
  1901.  
  1902. Note that these problems should not discourage experimenting, since they
  1903. have a low probability of affecting small programs.
  1904.  
  1905. =cut
  1906.  
  1907. OS/2 extensions
  1908. ~~~~~~~~~~~~~~~
  1909. I include 3 extensions by Andreas Kaiser, OS2::REXX, OS2::UPM, and OS2::FTP, 
  1910. into my ftp directory, mirrored on CPAN. I made
  1911. some minor changes needed to compile them by standard tools. I cannot 
  1912. test UPM and FTP, so I will appreciate your feedback. Other extensions
  1913. there are OS2::ExtAttr, OS2::PrfDB for tied access to EAs and .INI
  1914. files - and maybe some other extensions at the time you read it.
  1915.  
  1916. Note that OS2 perl defines 2 pseudo-extension functions
  1917. OS2::Copy::copy and DynaLoader::mod2fname (many more now, see
  1918. L<Prebuilt methods>).
  1919.  
  1920. The -R switch of older perl is deprecated. If you need to call a REXX code
  1921. which needs access to variables, include the call into a REXX compartment
  1922. created by 
  1923.     REXX_call {...block...};
  1924.  
  1925. Two new functions are supported by REXX code, 
  1926.     REXX_eval 'string';
  1927.     REXX_eval_with 'string', REXX_function_name => \&perl_sub_reference;
  1928.  
  1929. If you have some other extensions you want to share, send the code to
  1930. me.  At least two are available: tied access to EA's, and tied access
  1931. to system databases.
  1932.  
  1933. =head1 AUTHOR
  1934.  
  1935. Ilya Zakharevich, ilya@math.ohio-state.edu
  1936.  
  1937. =head1 SEE ALSO
  1938.  
  1939. perl(1).
  1940.  
  1941. =cut
  1942.  
  1943.